Skip to content

eacl/write-schema! with SpiceDB schema DSL parser & feature validation#55

Open
theronic wants to merge 39 commits intomainfrom
feature/write-schema-dsl
Open

eacl/write-schema! with SpiceDB schema DSL parser & feature validation#55
theronic wants to merge 39 commits intomainfrom
feature/write-schema-dsl

Conversation

@theronic
Copy link
Copy Markdown
Owner

Summary

This PR implements eacl/write-schema! to support SpiceDB schema DSL strings, enabling schema definition, validation, and safe updates.

Key changes:

  • Added instaparse dependency for parsing SpiceDB schema DSL.
  • Implemented eacl.datomic.spice-parser/->eacl-schema to transform parsed schema into EACL internal representation.
  • Implemented eacl.datomic.schema/write-schema! to:
    • Parse schema string.
    • Compute deltas (additions/retractions).
    • Validate retractions (check for orphaned relationships).
    • Transact changes to Datomic.
    • Store the schema string in Datomic.
  • Updated eacl.datomic.core/write-schema! and read-schema to use the new implementation.
  • Added tests for parser and schema writing logic.

Test plan

  • test/eacl/datomic/parser_test.clj - verifies parsing and transformation of SpiceDB schema DSL.
  • test/eacl/datomic/schema_test.clj - verifies write-schema! lifecycle, including additions, safe retractions, and orphan protection.

theronic and others added 30 commits October 23, 2025 10:17
Expanded the documentation for EACL, detailing its features, use cases, and advantages over external authorization systems. Included insights on modeling relationships directly in Datomic and the benefits of using EACL.
Revised the explanation of external authorization challenges and proposed solutions, enhancing clarity and flow.
Expanded the EACL documentation to clarify its features, benefits, and rationale for use. Added details about permission data handling, performance expectations, and comparisons with SpiceDB.
Clarified the challenges of syncing permission data with SpiceDB and emphasized the benefits of situating permission data in Datomic. Enhanced the explanation of EACL's performance and its suitability for various applications.
Rephrased and clarified several sections for better readability and understanding.
Updated wording for clarity and emphasis.
Updated performance metrics for EACL in documentation.
- Add instaparse dependency for parsing SpiceDB schema DSL.
- Implement `eacl.datomic.spice-parser/->eacl-schema` to transform parsed schema into EACL internal representation.
- Implement `eacl.datomic.schema/write-schema!` to:
    - Parse schema string.
    - Compute deltas (additions/retractions).
    - Validate retractions (check for orphaned relationships).
    - Transact changes to Datomic.
    - Store the schema string in Datomic.
- Update `eacl.datomic.core/write-schema!` and `read-schema` to use the new implementation.
- Add tests for parser and schema writing logic.
- Add documentation: status report and implementation plan.
Detailed review of the write-schema! implementation identifying:
- Critical missing validation for schema references
- Unsupported operators not being rejected
- Incomplete permission resolution logic
- Test gaps and recommendations for fixes

https://claude.ai/code/session_018SAGqvWbKvw5WNoMTXxcNV
- Added systematic review of each ADR decision point
- Identified missing fixtures.schema file (ADR requirement)
- Added Decision 8 breakdown for validation requirements
- Updated recommendations with P0 for fixtures.schema
- Enhanced test gaps section with fixture file requirement
- Updated conclusion with ADR compliance summary

https://claude.ai/code/session_018SAGqvWbKvw5WNoMTXxcNV
- Add instaparse/instaparse 1.5.0 dependency to deps.edn
- Remove unnecessary eacl.datomic.core require from spice_parser.clj that created a cyclic dependency (schema -> spice_parser -> core -> schema)
- Add :nrepl alias to deps.edn for MCP REPL integration
- Update CLAUDE.md with comprehensive nREPL setup instructions and MCP tool usage patterns

This fixes test failures caused by missing dependencies and circular namespace references.
Implements two-stage schema processing:
1. Parser: accepts complete official SpiceDB grammar (wildcards,
   subject relations, caveats, all operators, arrow functions, etc.)
2. Validator: enforces EACL restrictions via validate-eacl-restrictions

Key changes:
- Rewrote Instaparse grammar for full SpiceDB syntax support
- Added validate-eacl-restrictions with clear error messages
- Added validate-schema-references for relation/permission checking
- Updated read-schema to return rich map per ADR 012
- Added comprehensive parser and schema validation tests

All 23 tests pass (273 assertions).
Highlights gaps:
- P0: Comment support missing (blocking for production schemas)
- P1: Expiration traits and caveat definitions not parsed
- P2: self, .all(), subject relations, wildcards for future

Also documents architecture notes for potential refactoring.
1. Validation error messages now clearly indicate the unsupported feature:
   - "Unsupported operator: Exclusion (-). EACL only supports Union (+) at this time."
   - "Unsupported feature: Wildcard relation 'user:*' in doc/viewer..."
   - etc.

2. indexed_test.clj now loads schema via write-schema! with fixtures.schema
   instead of directly transacting Relation/Permission fixtures.
   - Demonstrates that the SpiceDB DSL schema is functionally equivalent
   - Clojure data fixtures retained for reference

All 23 tests pass (273 assertions).
Reviews improvements since initial review:
- All P0 issues from ADR compliance now addressed
- Schema reference validation implemented
- Unsupported operators now rejected
- fixtures.schema created and tested

Identifies new issues:
- P0: No comment support in grammar (blocking for production)
- P1: Self-permission semantic equivalence unverified
- P2: Minor dead code and inconsistent error sources

https://claude.ai/code/session_018SAGqvWbKvw5WNoMTXxcNV
Previous commit accidentally broke ->> threading macros when editing
indentation. Reverted test file to working state that still uses
write-schema! with fixtures.schema DSL.

All 24 tests pass (302 assertions).
…eronic/eacl into claude/review-eacl-write-schema-w1xt3
The alias `eacl` for `eacl.datomic.impl` conflicted with other files
that alias `eacl.core` as `eacl`. This caused reload-all failures:
"Alias eacl already exists in namespace eacl.datomic.fixtures"

Changed to just `:refer [Relation Relationship Permission]` since the
alias was unused.
Deleted indexed.clj.orig (tracked) and several untracked leftover files:
- spice_parser_{REMOTE,BASE,BACKUP,LOCAL}_35829.clj (merge conflict files)
- Various .orig backup files

These files were causing false cycle detection in Cursive IDE since the
old merge conflict files still referenced eacl.datomic.core.
Replace count-based and `some` predicate assertions with exact set
comparisons for more precise testing:

- Relations: check exact set of 3 relations
- Permissions: check exact set of 5 permissions
- Definitions: check exact set of definition keys

This catches regressions that count/some tests would miss.
…w1xt3

`eacl/write-schema!` with SpiceDB schema DSL parser & feature validation
- Schema Maintenance section: document write-schema! and read-schema
- Quickstart: use write-schema! with DSL string instead of manual Relation/Permission
- EACL Schema section: lead with DSL approach, add validation/update docs
- Schema Syntax: show DSL as primary, programmatic as advanced option
- Example Schema: simplify to just use DSL string
- Arrow Permissions: update to use DSL examples
- Limitations: remove outdated note about write-schema!/read-schema not supported
- Remove requirement to import Relation/Permission for basic usage
- API section: add write-schema! and read-schema to list
- Schema Maintenance: document write-schema! and read-schema
- Quickstart: use write-schema! with DSL string instead of manual Relation/Permission
- ReBAC section: update to use DSL example
- EACL Schema section: lead with DSL approach, add validation/update docs
- Arrow Permissions: update to use DSL examples
- Schema Syntax: show DSL as primary, programmatic as advanced option
- Example Schema: simplify to just use DSL string
- Limitations: remove outdated note about write-schema!/read-schema not supported
theronic and others added 7 commits February 2, 2026 15:36
…w1xt3

Update README.md for `eacl/write-schema!`
Resolved conflict in docs/index.md by removing the gRPC API note
to keep documentation focused on implemented features.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The map arity of can? asserted (= consistency/fully-consistent consistency)
which throws AssertionError when callers omit :consistency. Default to
fully-consistent instead.

Also add cursor-tree performance optimization plan document.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Regression detection benchmark for cursor-tree pagination performance.
Tests 4-path permission graph (server.view = account->admin + team->admin
+ vpc->admin + shared_admin) with 30 accounts x 500 servers = 15k total.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…lans from the past. not ideal to have it in main, but easier for git worktrees.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants